This document describes how to set up and use Apple NetFinder software from Apple Computer. Apple NetFinder lets you build up a Web site (or part of a Web site) quickly and easily by sharing folders or files much like you would using the file-sharing feature of the Mac OS.
Overview of Apple NetFinder
Apple NetFinder is a PowerMac only WebSTAR ACGI that runs on a Mac OS-based servers. After you install and launch Apple NetFinder, your Web server can serve out selected directories and files from mounted volumes and display to users a graphical interface similar to that of a Finder window, regardless of a user’s type of Web browser. The contents of one folder are displayed at a time (similar to FTP), organized as sortable columns of data. These columns are: Name, Size, Kind, and Date (see the following figure). The number of items in the current directory (visible to the user) are also shown.
By using the Users and Groups file-sharing privileges of the Mac OS, Apple NetFinder leverages security from a familiar source. Apple NetFinder shares only those items that have the equivalent access privileges set up by the administrator.
Installing and setting up Apple NetFinder
The following instructions assume you have already installed and set up your WebSTAR-based internet server.
• To install the Apple NetFinder software, place the “NetFinder” folder in a WebSTAR subfolder.
When you first launch Apple NetFinder, it creates any necessary folders and displays a software license agreement. After dismissing the license agreement screen you can either edit the preferences (described later in this document) or continue setting up Apple NetFinder.
The following folders are created automatically inside the NetFinder folder:
• NetFinder.acgi
• Volumes To Search---Put in this folder an alias to any volumes you want to be able to search. Apple NetFinder will ONLY search on volumes specified inside this folder and will only display items that the user in question has User and Groups access to.
IMPORTANT Don’t allow searches over the network; searches over the network are slow and consume all of the processing time.
• Graphics---This folder should contain GIFs that Apple NetFinder needs to display certain content types (such as folder icons, GIF icons, and so forth). A few basic default GIFs are created. Apple NetFinder will generate new ones on the fly, each one inside a folder whose name is the same as the first letter of the GIF file(s). For example, a TEXT.GIF file would be in the folder named “T.” If this folder is missing when Apple NetFinder is launched, Apple NetFinder will create it with the needed default GIFs.
• NetFinder_Top_Level---The contents of this folder is what Apple NetFinder displays when you call the ACGI from a Web browser. Place folders, files, and aliases in this root-level folder. (If you would like, you can also use an alias as the top-level folder. Remove the “NetFinder_Top_Level” folder and drag an alias of another volume or folder in its place and rename the alias “NetFinder_Top_Level”.) It is important that the folder has the name "NetFinder_Top_Level". If you want users to see another name for this folder, see the option for changing this in the Preferences Dialog below.
IMPORTANT You must remember to set the access privileges of this folder and its contents to those that wish your users to see.
• Log Folder---This folder is where Apple NetFinder will create log files (named as the date), with the contents of the log window appended to this file.
• Item Tracker Folder---This folder is where Apple NetFinder will create Item Tracker files (named as the date), and the information that appears in the Item Tracker Window will be saved here. This basically keeps track of the number of times each folderor file is entered or downloaded.
IMPORTANT All of the above folders are created automatically when you launch Apple NetFinder. Do NOT rename these, as Apple NetFinder expects them to have these names. It will create new copies if it doesn’t see them.
To access Apple NetFinder from a URL, type the HTTP path ending in “NetFinder.acgi”. This will start up Apple NetFinder and return the root folder’s contents to the user.
For greater flexibility, you can point directly at a folder in the NetFinder_Top_Level with the following syntax:
"$Root=" follows the ACGI name and then the folder name or forward slash delimited path followed by two of the Apple NetFinder delimiter characters '|' (vertical line). If this folder is not available, or the syntax isn’t correct, the user will be presented with the top-level default folder instead. You may want to utilize this feature to enable multiple entry points to your system.
Features seen by client
Columns
Column names are derived from the Finder’s resource. They should be in the same language as the operating system of the server (for Roman Script systems).
• # of items Shows number of items that are shown to the user.
• Name Name of item as seen in Finder.
• Size Size of non-folder items in kilobytes (1024 bytes).
• Kind Folder, application name, GIF, JPEG, application name document.
• Date Modification date of item in the Finder in the standard Finder format.
Icons displayed
• Folder Folders to be browsed.
• Finder icons These are files for which Apple NetFinder was able to create dynamic icons (copying them from the Finder). These can include applications as well as binaries to be downloaded.
• Application File will be downloaded to the client (generic icon is displayed when an 8-bit small icon isn’t defined for the Finder by this application).
• Text File can be displayed as HTML without downloading file first. If the file is a plain text file, Apple NetFinder will do some simple search/replace of carriage returns into an HTML format for line feeds. More importantly, Apple NetFinder supports conversion of SimpleText style information into HTML. This means that different font sizes, as well as bold, italics, and color information will be represented as HTML on the fly. (Some browsers only support a subset of these).
• Binary File will be downloaded to the client (generic plain binary icon for files whose application-defined icons cannot be found).
Additional links
• Parent Folder This link will take the user to the last folder viewed by them.
• Top Level This link will take the user to the top level of the Apple NetFinder hierarchy
• Leave NetFinder This link will take the user to the page that initially linked to Apple NetFinder.
Features for server
Accuracy
Every folder is shown on the fly, so the content is fully dynamic. Folders and files that are not shown are the following:
• invisible items
• aliases to items on an unmountable volume
• any item that doesn’t have read/search access in the Sharing Info dialog for that folder or items of the parent that matches that of the user.
Remote Network Volume Mounting
Apple NetFinder will try its hardest to make sure any aliases you want to use are available. If you have an alias to a remote volume, Apple NetFinder will attempt to mount that volume if it isn't mounted already. Apple NetFinder will attempt to mount the volume using the user name and password of the client accessing the folder the alias is contained in. If this fails Apple NetFinder will attempt to mount the volume via guest access. In the event that the server is not available or the user doesn't have the proper permissions, Apple NetFinder will not display the resolved alias item.
Binary transfer
Documents and applications not supported by WebSTAR’s suffix-mapping scheme (Apple NetFinder only regards filetype and creator and ignores suffixes) are converted to a binhex format and placed into a temporary storage folder and sent to the client with the binhex suffix. This will cause the client’s browser to unbinhex the file to the original format.
MacRoman -> Latin1 translation
Files and folders that have high ASCII character names or content will be translated where desired to their Latin1 equivalent. Some of these may be translated to multiple-character low ASCII combinations (for example, ™ -> (tm)). This translation is not necessary for Macintosh clients who have MacRoman installed and support the MacRoman (Netscape only). Because the translation isn’t done for these clients, connection times are faster and your text files and file/folder names are more accurately displayed.
Expanded icon support
Apple NetFinder will generate the application and data file icons that are shown in the Finder. Apple NetFinder will create a GIF file in its Graphics folder for the particular file type by looking up the file’s application and reading out the icon information inside the application. If the application doesn't have a small eight bit icon ('ics8') for a particular file type, Apple NetFinder will use the default icon.
Search
The user has the ability to perform searches on the volume catalogs pointed to by aliases in the Volumes To Search folder. This search will look for file or folder names that contain the search string. If more than the maximum number of documents are found, only the maximum are listed (whatever you have set in the Preferences dialog; this currently defaults to 200). Use the following format to do a search:
Enter Your Search Here: <input size=20 type=text name="query"> <input type="submit" value="Search">
HTML Header and Footer Support
You can customize the look and feel of your Apple NetFinder pages. By adding "folder_header.html" and/or "folder_footer.html" file(s) to the folder where your Apple NetFinder.acgi program resides, Apple NetFinder will read the contents of these files and put the text before and after the folder listing. By adding "text_header.html" and/or "text_footer.html", Apple NetFinder will read the contents and add the them to the beginning and/or end of any Simple Text document that Apple NetFinder translates into html. You can use this to display graphics, provide your own tool bar, provide a link to your top level web page, or whatever else you choose to make your site better.
IMPORTANT You do NOT want to have any of the following tags in your header or footer files: <HTML> <TITLE> </TITLE> <BODY> </BODY> </HTML> as NetFinder is already generating these tags and placing your html text in the appropriate places. By adding your own <html> tag, you can cause unpredictable behavior for your users as browsers don't tend to like more than one of these and can easily get confused.
Security
The Apple NetFinder application has a default top-level folder. The site administrator places files/folders/aliases inside this folder. The user is shown the contents of this folder with the initial call to the ACGI.
Apple NetFinder supports the Users and Groups scheme of Mac OS file sharing and AppleShare. Users are asked to supply a name and password if they haven’t already registered with WebSTAR. A user has access to items the user could access if logged in to the server through AppleShare. To access Apple NetFinder as a guest, the user can type the name “Guest” or “Anonymous” with no password (see the following figure). In this case the user will only be able to see items that are shared as guest-accessible items. Apple NetFinder’s default behavior is to allow only guest access (no security password dialogs are displayed). To change this, select the Users And Groups option in the Preferences dialog.
IMPORTANT A current limitation is that WebSTAR converts name and password to uppercase strings; while the name is not a problem, the passwords in the Users and Groups setup should all be uppercase, or all lowercase!
IMPORTANT Also make sure that you set your personal filesharing / AppleShare privileges for all the content you want your users to access. This includes the folder "NetFinder_Top_Level+.
Threading
Apple NetFinder is threaded to provide better response time to each client.
Log file
The Log file is filled with exactly the same information as the Log window, but it has no size limit (other than that of the drive). The Log file is broken up into files with the corresponding date as their name.
Log window
The Log window shows the administrator information about each connection. It lists things like the client’s IP address as well as what item is being accessed. The log rolls over automatically when it reaches 32K.
Item Tracker window
The Item Tracker window shows the user a list of folders and files that have been accessed since the last time Apple NetFinder was launched. It also lists the number of times that folder or file has been accessed (sorted by number of hits) as well as the number of times each folder or file has been accessed since the last time the information was zeroed out (Zero Totals under the Stats menu).
Preferences dialog
The Apple NetFinder Preferences dialog (located under the Edit menu) allows the site administrator to set some of the parameters that NetFinder uses. The following options are available (see the following figure):
• Top Level Folder Name---This is the name that gets sent to the client as the title of the top level folder. If you would like the user to see a name that is different from "NetFinder_Top_Level" when they first access your Apple NetFinder heirarchy, change the name here.
IMPORTANT Do not change the name of the actual folder in the Finder that contains your content. Apple NetFinder looks for this folder by name and create a new one if it doesn't see it.
• Use true site name for links---This will cause Apple NetFinder to use the server address that it receives from WebSTAR. Choose this option if you want to create a round robin mirroring scheme where each user gets passed off to a different Apple NetFinder Server. Once the user is accessing data from a particular Apple NetFinder machine, the links are created specifically for that machine (and Apple NetFinder saves state for each user during that session). If you allow users to search your site, Apple NetFinder will automatically generate these reverse links.
• Auto Quit---You can choose to have Apple NetFinder automatically quit after a certain amount of idle time. This may be useful to you if you have a number of different server applications/cgis and your traffic is low. Apple NetFinder will get automatically launched by WebSTAR if a user requests it by url.
• Display NetFinder Toolbar---This is the "toolbar" that Apple NetFinder generates for you at the bottom of the folder listing. It consists of up to three links: Parent Folder | Top Level | Leave NetFinder. The first two will not show up initially as the user will already be at the top level and have no Parent Folder to go to. The last link is for users that arrive at Apple NetFinder from an html page. This link will take them back to the page that brought them here. If the user accesses Apple NetFinder by typing in the URL directly, this link will not show up.
• Access Privileges---The Guest Access Only setting is to allow your users to access your site (as long as items in your hierarchy are set to guest access) without worrying about security dialogs. The Users And Groups Access Levels setting will force each user to be logged in as a WebSTAR legitimate user and will allow a user to see only the contents that coincide with the Users and Groups data file on that server. Users can also log in as “Guest” or “Anonymous” without a password to get guest access privileges.
• Max size of text documents to display---This is the number of kilobytes you will allow Apple NetFinder to parse through and send on to the client’s Web browser. Apple NetFinder does some character translations on the fly but large files may slow it down (and might be too large for the client’s Web browser!). Text files with size greater than this number are sent back to the user as a binary-encoded file.
• Max number of items to display---This is the limit on the number of files and folders Apple NetFinder will show in its folder view. If a folder has more than this number of items, the list will get truncated to this number.
